Inside Macintosh: QuickDraw GX Graphics /

Chapter 4 - Geometric Operations / Geometric Operations Reference

Functions / Finding Geometric Information About Shapes

GXGetShapeArea

You can use the GXGetShapeArea function to determine the area covered by a specific contour of a shape's geometry.

gxWide *GXGetShapeArea(gxShape source, long index, gxWide *area);

source

A reference to the shape containing the contour whose area you want to determine.

index

The number of the contour whose area you want to determine. You may specify a value of 0 for this parameter to indicate you want to determine the area of the entire shape.

area

A pointer to a gxWide value. On return, this value indicates the area covered by the contour.

function result

The area covered by the contour. (This value is the same as the value
returned in the area parameter.)

DESCRIPTION

The GXGetShapeArea function returns the area covered by the contour specified by the index parameter of the shape indicated by the source parameter. This function considers only the geometry of the source shape--it does not consider the shape fill of the shape. The same geometry returns the same area whether the shape has one of the framed fills, an even-odd fill, a winding fill, or one of the inverse fills.

Some shapes have overlapping contours with the same contour direction. (When drawing these shapes, QuickDraw GX fills these overlapping areas if the shape has a winding fill and does not fill these areas if the shape has an even-odd fill.) The GXGetShapeArea function counts these overlapping areas twice. To correct this calculation, call the GXSimplifyShape function before calling the GXGetShapeArea function:

• For shapes with a winding shape fill, the GXSimplifyShape function eliminates the inner contour and, therefore, the GXGetShapeArea function counts the overlapping area only once.
• For shapes with an even-odd shape fill, the GXSimplifyShape function reverses the contour direction of the internal contour, and therefore the GXGetShapeArea function does not count the overlapping area at all.

This function measures the shape area as defined in the shape's geometry; it does not consider transformations to the shape made by the shape's transform.

For empty shapes, point shapes, and line shapes, this function posts the error shape_does_not_have_area. For full shapes, it posts the error illegal_type_for_shape.

If you provide a target shape that is not one of the geometric shape types, this function performs the actions described in the following table:

Shape type	Action taken
bitmap	Returns the bitmap height multiplied by the bitmap width
picture	Returns the sum of the areas of the picture items
text	Converts to path shape and finds area
glyph	Converts to path shape and finds area
layout	Converts to path shape and finds area

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
parameter_is_nil
shape_does_not_have_area	(debugging version)
Warnings
index_out_of_range
contour_out_of_range

SEE ALSO

For examples using this function, see "Finding the Area of a Shape" beginning on page 4-45.

For a discussion of shape fills, see Chapter 2, "Geometric Shapes," in this book

To simplify a shape before measuring its area, use the GXSimplifyShape function, described on page 4-76.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help